jdbc:teiid:<vdb-name>@mm://host1:31000,host1:31001,host2:31000;version=2
A group of Teiid Servers in the same JBoss AS cluster may be connected using failover and load-balancing features. To enable theses features in their simplest form, the client needs to specify multiple host name and port number combinations on the URL connection string.
jdbc:teiid:<vdb-name>@mm://host1:31000,host1:31001,host2:31000;version=2
If you are using a DataSource to connect to Teiid Server, use the "AlternateServers" property/method to define the failover servers. The format is also a comma separated list of host:port combinations.
The client will randomly pick one the Teiid server from the list and establish a session with that server. If that server cannot be contacted, then a connection will be attempted to each of the remaining servers in random order. This allows for both connection time fail-over and random server selection load balancing.
Post connection fail over will be used, if the autoFailover connection property on JDBC URL is set to true. Post connection failover works by sending a ping, at most every second, to test the connection prior to use. If the ping fails, a new instance will be selected prior to the operation being attempted. This is not true "transparent application failover" as the client will not restart the transaction/query/recreate session scoped temp tables, etc. So this feature should be used with caution.
Post connection load balancing can be utilized in one of two ways. First if you are using TeiidDataSource and the Connections returned by Teiid PooledConnections have their close method called, then a new server instance will be selected automatically. However when using driver based connections or even when using TeiidDataSource in a connection pool (such as JBoss AS), the automatic load balancing will not happen. Second you can explicitly trigger load balancing through the use of the set statement:
SET NEWINSTANCE TRUE
<datasources>
<datasource jndi-name="java:/teiidDS" pool-name="teiidDS">
<connection-url>jdbc:teiid:{vdb}@mm://{host}:31000</connection-url>
<driver>teiid</driver>
<pool>
<prefill>false</prefill>
<use-strict-min>false</use-strict-min>
<flush-strategy>FailingConnectionOnly</flush-strategy>
<check-valid-connection-sql>SET NEWINSTANCE TRUE</check-valid-connection-sql>
</pool>
<security>
<user-name>{user}</user-name>
<password>{password}</password>
</security>
</datasource>
<drivers>
<driver name="teiid" module="org.jboss.teiid.client">
<driver-class>org.teiid.jdbc.TeiidDriver</driver-class>
<xa-datasource-class>org.teiid.jdbc.TeiidDataSource</xa-datasource-class>
</driver>
</drivers>
</datasources>
Teiid by default maintians a pool of extra socket connections that are reused. For load balancing, this reduces the potential cost of switching a connection to another server instance. The default setting is to maintain 16 connections (can be set via org.teiid.sockets.maxCachedInstances in a teiid-client-settings.properties file). If you're client is connecting to large numbers of Teiid instances and you're using post connection time load balancing, then consider increasing the number of cached instances. You may either set an analogous system property or create a teiid-client-settings.properties (see the teiid-client-settings.orig.properties file in the client jar) file and place it into the classpath ahead of the client jar.
Session level temporary tables, currently running transactions, session level cache entries, and PreparedPlans for a given session will not be available on other cluster members. Therefore, it is recommended that post connection time load balancing is only used when the logical connection could have been closed, but the actual connection is reused (the typical connection pool pattern).
Server discovery, load balancing, fail over, retry, retry delay, etc. may be customize if the default policy is not sufficient. See the org.teiid.net.socket.ServerDiscovery interface and default implementaion org.teiid.net.socket.UrlServerDiscovery for how to start with your customization. The UrlServerDiscovery implemenation provides the following: discovery of servers from the URL hosts (DataSource server/alternativeServers), random selection for load balancing and failover, 1 connection attempt per host, no biasing, black listing, or other advanced features. Typically you'll want to extend the UrlServerDiscovery so that it can be used as the fallback strategy and to only implement the necessary changed methods. It's important to consider that 1 ServerDiscovery instance will be created for each connection. Any sharing of information between instances should be done through static state or some other shared lookup.
Your customized server discovery class will then need to be referenced by the discoveryStategy connection/DataSource property by its full class name.
You may also choose to use an external tcp load balancer, such as haproxy. The Teiid driver/DataSource should then typically be configured to just use the single host/port of your load balancer.